Somari Documentation by PalaceSwitcher (2021-12-29)

Any ROM locations marked with [C] are assembly code and should be modified with caution.
-----Tilemap Data-----
3094C - 30963:	Title Card PC Pointers
30964 - 3098F:	Green Hill Title Card
30990 - 309BB:	Marble Title Card
309BC - 309E7:	Spring Yard Title Card
309E8 - 30A13:	Labyrinth Title Card
30A14 - 30A3F:	Star Light Title Card
30A40 - 30A6B:	Scrap Brain Title Card (Unused)
30A6C - 30A97:	Final Title Card
30A98 - 30AC3:	Special Title Card
30AC4 - 30AEF:	"ZONE" Title Card Text
30AF0 - 30B47:	"SPECIAL STAGE" Title Card
30B48 - 30B9F:	"SOMARI HAS PASSED" Title Card
Note: The tilemaps below are compressed and have their own format.
30BA0 - 30BA5:	Tilemap Screen PC Pointers
30BA6 - 30F42:	Title Screen
30F43 - 310B4:	Level Select
310B5 - 3111C:	Level Passed Screen

-----Palette Data-----
3D5D8 - 3D5EF:	Palette Pointers
3D5F0 - 3D74F:	Palette Data (Level/Title)

-----Level Data-----
-Object Layout Format-
Object layouts have 64 byte "lists" containing certain data for all the objects in a level. Here's the order of these lists in memory:
> 1st List = Object IDs
> 2nd List = Object X Positions
> 3rd List = Object X Screens?
> 4th List = Object Y Positions
> 5th List = Object Y Screens
> 6th List = Object Attributes?
1B010:	Green Hill Zone Act 1 Object Layout
32A24 - 32A63:	Act Spawn Positions [0x4 per act]
> 0x1 = X Screen
> 0x2 = X Scroll Position?
> 0x3 = Y Screen
> 0x4 = Y Scroll Position?

-----Sprite Mappings/Attributes-----
-Mapping Header-
> 0x1 = Tile Width (Excluded in most cases)
> 0x2 = Tile Height (Excluded in most cases)
> 0x3 = 1K CHR Bank (This byte is excluded or ignored in some cases)
> 0x4 = Relative X Positioning?
> 0x5 = Relative Y Positioning?
> 0x6 - 0x7 = Attribute Pointer (Excluded in some cases)
223A8 - 223AB:	Wrecking Ball Offset Pointers
223AC - 223AF:	Wrecking Ball Attributes
223BF - 223CE:	Robotnik Zone Pointers
223CF - 2242E:	Robotnik Attributes
2242F - 2244A:	GHZ Robotnik Mapping Pointers
2244B - 225C3:	GHZ Robotnik Mappings (1 unused frame, no attribute pointer)
225C4 - 2262E:	Wrecking Ball Mappings
2262F - 2264A:	MZ Robotnik Mapping Pointers
2264B - 227CA:	MZ Robotnik Mappings
24CCF - 24CDA:	Smoke Puff Mappings
24CE3 - 24CEA:	Monitor Mapping Pointers
24CEB - 24CF3:	Ring Monitor Mappings
24CF4 - 24CFC:	Checkpoint Monitor Mappings (Unused)
24CFD - 24D05:	Life Monitor Mappings
24D06 - 24D0E:	Speed Monitor Mappings (Unused)
24D0F - 24D17:	Invincibility Monitor Mappings
24D18 - 24D20:	Shield Monitor Mappings
24D21 - 24D29:	Static Monitor Mappings
24D2A - 24D68:	Monitor Attributes
24D69 - 24DA4:	Buzz Bomber Mappings+Attr
24DA5 - 24DE4:	Buzz Bomber Shooting Mappings+Attr
24DE5 - 24DF6:	Chomper Mappings
24DF7 - 24DFE:	Crabmeat Mapping Pointers
24DFF - 24E46:	Crabmeat Mappings+Attr
24E47 - 24EA6:	Newtron Mappings+Attr
24EA7 - 24F46:	Newtron Flying Mappings (2 unused frames)
24F47 - 24F5E:	Animal Mappings
24F5F - 24F7E:	Ring Mappings+Attr
25951 - 2595B:	Ground Flame Mapping Pointers+Attr
2595C - 2598B:	Ground Flame Mappings
2598C - 25991:	Vertical Fireball Mappings
25992 - 25997:	Horizontal Fireball Mappings
25998 - 259B8:	Spike Mappings (1 unused frame)
259B9 - 259C0:	Moving Platform Mappings
259C1 - 25A08:	Caterkiller Mappings
25A09 - 25A50:	Batbrain Mappings (1 unused frame)
25A51 - 25AB0:	Spikes Badnik Mappings
308DF - 30916:	Title Card Circle Sprite
30917 - 30919:	Title Card "Act" Text
3091A - 3092B:	Title Card Act Numbers
3111D - 3119C:	Title Card Attributes
3803D - 38096:	Player Animation Pointers
38097 - 384C2:	Player Animations [0x4 per frame]
-Player Animation Format-
> 0x1 - 0x2 = Frame Pointer
> 0x3 = Frame Length+1?
> 0x4 = End Byte
384C3 - 384D4:	Player Attribute Pointers
384D5 - 38954:	Player Attributes
3895D - 38F9A:	Player Mappings (Several unused frames, no attribute pointers, has pointers behind each frame for mirrored and normal variants, specifies width and height)

-----Music Data-----
34010 - 34089:	Sound Data Pointers
34810 - 348F1:	Title
348F2 - 34A5F:	Invincibility
34A60 - 34AF9:	Level Complete
34AFA - 34D19:	Green Hill Zone
34D1A - 34F21:	Marble Zone
34F22 - 35275:	Spring Yard Zone
35276 - 354FA:	Labyrinth Zone
354FB - 357C5:	Star Light Zone
357C6 - 3595E:	Special Stage
3595F - 35AF1:	Boss
35AF2 - 35C26:	Drowning
35C27 - 36CAB:	Game Over
35CAC - 35D0C:	Get Emerald (Unused)
35D0D - 35D60:	Get Continue (Unused)
35D61 - 35D71:	Skidding
35D72 - 35D99:	Ring
35D9A - 35DB2:	Jump
35DB3 - 35DDF:	Lose Rings
35DE0 - 35DF0:	Break
35DF1 - 35E01:	Spring (Unused)
35E02 - 35E13:	Air Bubble
35E14 - 35E2D:	Spindash
35E2E - 35E3E:	Explosion
35E3F - 35E51:	Checkpoint (Unused)
35E52 - 35E62:	Unknown/Unused

-----Misc-----
2CBAC:	Loop Diagonal X Velocity? (Changing it fixes the ring bug) [C]
3028F - 302CD:	Sound Test Pointers
302CE - 302F1:	Level Select Cursor Positions
302F2 - 30313:	Zone/Act Order
303FF - 30406:	Zone Music Settings
30414 - 3041D:	Title Card PC Pointers?
32728 - 3276F:	Zone BG Banks [0x8 per level]
> 0x1 = BG Bank 1
> 0x2 = BG Bank 2
> 0x3 = BG Bank 3
> 0x4 - 0x7 = Animated BG Banks
> 0x8 = Unused?
36010 - 6301F:	HUD Digit Mappings
3A023:	HUD Ring X Position [C]
3A028:	HUD Ring Y Position [C]
3A02D:	HUD Ring Attributes [C]
3A032:	HUD Ring Second Tile [C]
3A036:	HUD Ring Animation Speed (Amount of frames between each tile change) [C]
3A03A:	HUD Ring First Tile [C]
3A044:	Ring 100s Digit X Position [C]
3A049:	Ring 100s Digit Y Position [C]
3A04E:	Ring 100s Digit Attributes [C]
3A060:	Ring 10s Digit X Position [C]
3A065:	Ring 10s Digit Y Position [C]
3A06A:	Ring 10s Digit Attributes [C]
3A51A - 3A539:	Player Walk/Run Cycle Animation IDs
3A55A - 3A55E:	Player Idle Animation IDs



-----RAM Map-----
$0002:	Hardware Scroll X Position
$0003:	Hardware Scroll Y Position
$0006:	Frame Counter
$0007:	Frame Counter (Duplicate)
$000A:	Player X Screen
$000B:	Player X Coords
$000C:	Player Y Screen
$000D:	Player Y Coords
$000E:	Player X Screen (Duplicate)
$000F:	Player X Coords (Duplicate)
$0010:	Player Y Screen (Duplicate)
$0011:	Player Y Coords (Duplicate)
$0012:	Player Sprite X Position
$0013:	Player Sprite Y Position
$0014:	Player X Speed
$0015:	Player Y Speed
$0016:	Player Animation
00 = Doing Nothing/Idle
01 - 03 = Walking
04 - 05 = Running
06 = Bouncing off spring
07 = Skidding
08 = Jump
09 = Dead
0A = Hurt
0B = Ducking
0C = Looking up
0D = Pushing against wall
0F = Idle animation (waiting)
10 = Idle animation (laying down)
11 = Balancing 1 (unused)
12 = Balancing 2 (unused)
13 = Balancing 3 (unused)
15 - 17 = Walking (sideways)
18 - 19 = Running (sideways)
1A - 1C = Walking (angled)
1D - 1E = Running (angled)
1F = Spindash
20 = Rolling
21 - 23 = Walking (angled 2)
24 - 25 = Running (angled 2)
$0017:	Player Animation Frame?
$0019:	Player Movement
> Bit 0 = Horizontal Direction (0 = Right, 1 = Left)
> Bit 1 = Diagonal Flag? (Unknown, is set when player is on a loop or facing left)
> Bit 2 = Vertical Direction (0 = Down, 1 = Up)
> Bit 6 = Player Horizontal Sprite Flip (0 = Facing right, 1 = Facing left)
$001A:	Player Status
Bit 1 = Shield Flag (0 = No Shield, 1 = Shield)
Bit 2 = Ball Flag (0 = Not in ball, 1 = In ball)
$001B - $001C:	Player Frame Pointer
$001D:	Player Action
$001E:	Player Action (Duplicate)
$003A:	Player Sprite Width
$003B:	Player Sprite Height
$003C:	Open Sprite Slot (Always multiple of 4, contains index for the next open sprite slot)
$0040 - $0044:	Metasprite Column Alignment
$0081:	Music Register
$0082:	Sound Effect Register
$0084:	Horizontal Interrupt Mode
> 00 = None
> 01 = Title Screen
> 02 = Title Card
$0086:	Title Card Status
> 00 = Nothing set
> 01 = Zone name slide
> 02 = "ZONE" text slide
> 03 = All text slide
> 04 = All text slide out
> 05 = Blank
$0099:	Invincibility Timer
$009A:	Drown Timer/Underwater Flag
$009B:	Invulnerability Timer
$009E:	Object Behavior?
> 00 = Breakable
> 01 = Ring
> 02 = Damage
$009F:	Object Hitbox Width Buffer
$00A0:	Object Hitbox Height Buffer?
$00AE:	Scroll Lock Flag
$00AF:	Time Over Flag
$00B0:	Time Over Text State?
$00B2:	Event Trigger
> 00 = Nothing
> 01 = Continue Screen (unused)
> 02 = Reset level?
> 03 = Game Reset
> 04 = Level Complete
> 05 = Ending
$00B3:	Continue Count (unused)
$00B5:	Level End Sequence State?
$00B6:	Capsule State
> 00 = Not on screen
> 01 = Not fully on screen
> 02 = On screen/Idle
> 03 = Capsule Hit (Player Running)
> 04 = Skip to state 05
> 05 = Exploding
> 06 = Skip to state 07
> 07 = Skip to state 08
> 08 = Releasing animals
> 09 = Skip to state 00/disable capsule
$00B7:	Right Screen Edge Lock Flag (Used to fully restrict game to one screen)
$00BC:	Boss State
$00CC:	Boss Health
$00D3:	Wrecking Ball X Position
$00D5:	Wrecking Ball Y Position
$00E7:	Next Act Number
$00E8:	Next Zone Number
$00E9:	100 Ring/Special Stage Flag
$00EB:	Pause Flag
$0300:	Buttons Held
$0302:	Buttons Pressed
$032B:	1st 2K Sprite Bank
$032C:	2nd 2K Sprite Bank
$032D:	1st 1K BG Bank
$032E:	2nd 1K BG Bank
$032F:	3rd 1K BG Bank
$0330:	4th 1K BG Bank
$0331:	Current Palette
$0334:	Timer Frame Count
$0335:	Player Idle Animation Timer
$0336:	Ring Count 100s Digit (X00)
$0337:	Ring Count 10s Digit (0X0)
$0338:	Ring Count 1s Digit (00X)
$0339:	Timer Minutes Digit (0X:00)
$033A:	Timer Seconds 10s Digit (00:X0)
$033B:	Timer Seconds 1s Digit (00:0X)
$033C:	Life Count Digit (X)
$0349 - $034C:	Animated BG Banks
$037B:	Score 100 Thousandths Digit (X00000)
$037C:	Score 10 Thousandths Digit (0X0000)
$037D:	Score Thousandths Digit (00X000)
$037E:	Score 100s Digit (000X00)
$037F:	Score 10s Digit (0000X0)
$0380:	Score 1s Digit (00000X)
$04E7:	Level PRG Bank?
$04EA:	Zone Number
> 00 = Green Hill
> 01 = Marble
> 02 = Spring Yard
> 03 = Labyrinth
> 04 = Star Light
> 05 = Scrap Brain (unused remnants)
> 06 = Final
> 07 = Special Stage
$04EB:	Act Number
> 00 = Act 1
> 01 = Act 2
> 02 = Act 3
$0500 - $0516:	Object Slots
> 01 = Buzz Bomber
> 02 = Buzz Bomber (Shooting)
> 03 = Chopper
> 04 = Crabmeat
> 05 = Crabmeat (Shooting)
> 06 = Newtron
> 07 = Newtron (Shooting)
> 08 = Newtron (Moving)
> 09 = 1UP Monitor
> 10 = Ring Monitor
> 11 = Checkpoint Monitor (Unused)
> 12 = Life Monitor
> 13 = Speed Shoes Monitor (Unused)
> 14 = Invincibility Monitor (Unused)
> 15 = Shield Monitor
> 16 = Bouncing Ring
> 18 = Freed Rabbit
> 19 = Freed Bird
> 1A = Buzz Bomber Projectile
> 1B = Crabmeat Projectile
> 1C = Newtron Projectile
> 1D = Exploding Badnik
> 1E = Lava Fireball
> 20 = Single Left Wall Spike
> 22 = Single Right Wall Spike
> 24 = Triple Left Wall Spikes
> 26 = Triple Right Wall Spikes
> 28 = Caterkiller
> 29 = Swinging Platform
> 2A = Ground Flames
> 2B = Horizontal Platform
> 2E = Goal Sign
> 2F = Goal Sign (Touched)
> 30 = Spikes Badnik
> 31 = Spinning Spike Ball (Fast)
> 32 = Spinning Spike Ball
> 33 = Small Spinning Spike Ball
> 34 = Horizontal Spike Ball
> 35 = Vertical Spike Ball
> 38 = Horizontal SYZ Platform
> 39 = Small Horizontal SYZ Platform
> 3A = Vertical SYZ Platform
> 3B = Vertical Small SYZ Platform
> 3C = Horizontal SYZ Platform (Alt)
> 3D = Small Horizontal SYZ Platform (Alt)
> 3E = Small Spinning Spike Ball (Unused variant?)
> 3F = Small Horizontal SYZ Platform (Alt 2)
> 40 = Jaws
> 41 = Tiny Left Fireball
> 42 = Tiny Right Fireball
> 43 = Bubble Generator
> 44 = Large Air Bubble
> 45 = Small Air Bubble
> 46 = Medium Air Bubble
> 47 = Red Orbinaut
> 48 = Red Orbinaut Spike
> 49 = LZ Right Spear
> 4A = LZ Left Spear
> 4B = LZ Up Spear
> 4C = LZ Down Spear
> 4D = LZ Upwards Platform
> 4E = LZ Horizontal Platform
> 4F = LZ Vertical Platform
> 50 = Purple Orbinaut
> 51 = Bomb
> 52 = Ceiling Bomb
> 53 = Burrobot
> 58 = Final Boss Orb 4
> 59 = Final Boss Orb 3
> 5A = Final Boss Orb 2
> 5B = Final Boss Orb 1
> 5C = Final Boss Orb Spawner
> 5D = Final Boss Orb (Moving)
> 60 = Cluster Explosion
> 61 = MZ Robotnik Fireball
> 62 = MZ Robotnik Left Fire Spread
> 63 = MZ Robotnik Right Fire Spread
> 64 = MZ Robotnik Jumping Fireball
$0517 - $052D:	Object X Position
$052E - $0544:	Object X Screen
$0545 - $055B:	Object Y Position
$055C - $0572:	Object Y Screen
$0573 - $0589:	Object Status
$058A - $05A0:	Misc Object Variables
$05A1 - $05B7:	Object X Distance From Player
$05B8 - $05CE:	Object X Screen Distance From Player
$05CF - $05E5:	Object Y Distance From Player
$05E6 - $05FC:	Object Y Screen Distance From Player
$0601:	Level Select Input Counter
$0602:	Level Select Status
> 00 = Not active
> 01 = Input code failed
> 02 = Input code successful
$0604:	Level Selected
$0605:	Sound Select Number